Migration-Extension Interface

Purpose

The Migration-Extension Interface allows application developers to migrate Microsoft® Windows® 95 and Windows 98 applications when the user upgrades from that operating system to Microsoft Windows 2000. The Migration-Extension Interface is a developer-created DLL that the Windows 2000 setup application uses to correctly install and configure the application.

Where Applicable

The Windows 2000 setup application attempts to ensure that all applications remain properly installed and configured after the operating system is upgraded, but there are specific problems that the Windows 2000 setup application cannot resolve. An application developer should create a Migration-Extension Interface migration DLL if the application meets the following requirements.

Developer Audience

Application developers might require the Migration-Extension Interface if their application performs any of the following operations:

  • Writes to different registry locations on Windows 95/98 than on Windows 2000.

  • Writes different registry values to the same registry locations.

  • Installs different run-time files.

  • Installs different versions of files that are common to Windows 95/98 and Windows 2000.

  • Makes operating system–specific calls on Windows 95/98 that are not available on Windows 2000.

Run-time Requirements

Windows 95/98, Windows 2000.

See Also

Setup API

Overview

General information about Migration-Extension Inferface

Reference

Documentation of Migration-Extension Interface functions.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Friday, February 09, 2001.


Roadmap to Migration-Extension Interface Documentation

Ideally, applications designed for the Microsoft® Windows® 95 and Microsoft Windows 98 operating systems behave identically under Microsoft Windows 2000. However, a Windows 95/98 application can operate differently — or not at all — after the computer on which the application is installed has been upgraded to Windows 2000, and users might have to reinstall the application.

To prevent this problem, Microsoft provides the Migration-Extension Interface, an extension to the Windows 2000 setup application. This extension assists the Setup program in determining how to install and configure an application so that it will work correctly with Windows 2000. To use the migration extension, you write a migration DLL (Migrate.dll) that the Setup program utilizes.

This programmer's reference explains how to create a migration DLL and is divided into the following sections:

  • About the Migration-Extension Interface

    Provides details on the migration process, including information on Migrate.dll and Migrate.inf.

  • Using the Migration-Extension Interface

    Provides details on how to use the Migration-Extension Interface. Includes a sample Migrate.inf file.

  • Migration-Extension Interface Reference

    Includes migration DLL functions.


About the Migration-Extension Interface

While Setup attempts to ensure that all applications remain properly installed and configured after the operating system is upgraded, there are specific problems that Setup cannot resolve. These include problems caused by applications that do the following:

  • Write to different registry locations on Microsoft® Windows® 95 and Windows 98 than on Microsoft Windows 2000.
  • Write different registry values to the same registry locations.
  • Install different run-time files (.dll, .exe, and so on).
  • Install different versions of files that are common to Windows 95/98 and Windows 2000.
  • Make operating-system-specific calls on Windows 95/98 that are not available on Windows 2000.

You can use the Migration-Extension Interface to instruct Setup to correct these problems during the Windows 2000 upgrade.

This section contains the following topics:

  • How the migration process works

    Explains how migration fits into the Windows 2000 upgrade process.

  • Migrate.dll

    Describes the overall structure and processing order of the migration extension functions.

  • How migration DLLs are processed

    Describes the order in which the migration extension functions are called and a brief description of each function.

  • Migrate.inf

    Details the format and content of the file your migration DLL uses to pass information to Windows 2000 Setup.


How the Migration Process Works

The Migration-Extension Interface fits into the upgrade process as follows:

  1. A user installs the original application on a Windows 95/98-based computer. The original application developers include the Migrate.dll and Migrate.inf in the same directory, and add any other associated files on the distribution media or on the World Wide Web site from which the user installs the application.
  2. Sometime later, the user runs the Windows 2000 Setup program, which prompts the user for the location of the migration DLLs.
  3. Setup locates the Migrate.dll based on the user's input and runs it for the selected application. While the Windows 2000 setup application is still running in Windows95/98, it passes the corresponding Migrate.inf file to the application's Migrate.dll.
  4. The Migrate.dll modifies the Migrate.inf file with the relevant information and passes the Migrate.inf file back to Windows 2000 Setup, still under Windows 95/98.
  5. The application's Migrate.dll must perform the functions that were listed in the Migrate.inf file to properly set up and configure the application to run under Windows 2000.


Migrate.dll

The migration DLL is a standard Win32®-based DLL that you create. It is called by Windows 2000 Setup at different times during the upgrade process to perform a custom migration of your application.

At a minimum, a migration DLL must have the following Setup-defined exported functions:

  • QueryVersion
  • Initialize9x
  • MigrateUser9x
  • MigrateSystem9x
  • InitializeNT
  • MigrateUserNT
  • MigrateSystemNT

Your migration DLL can contain additional functions. However, if any of these seven functions are missing from a migration DLL, Setup will not load and process the migration DLL, and your application will not migrate.


How Migration DLLs are Processed

This section describes the order in which the functions in the migration DLL are called and a brief description of each function. Note that if any of the required seven functions are not present, Setup skips your Migrate.dll, and your application does not migrate to the new system.

During the initial phase of Windows 2000 Setup (that is, while Windows 95/98 is still running), the following Migrate.dll functions are called in the order listed.

Function | Caller | Reason for Call
DllMain (DLL_PROCESS_ATTACH) | Windows 95/98 | Load the migration DLL from the installation media.
QueryVersion | Setup | Obtain application ID information (such as the product ID and version number) and determine if further processing is necessary. After successful processing, the relevant files are copied to the user's hard disk.
DllMain (DLL_PROCESS_DETACH) | Windows | Unload the migration DLL.
DllMain (DLL_PROCESS_ATTACH) | Windows | Load the migration DLL from its new location on the local hard disk.
Initialize9x | Setup | Prepare Migrate.dll for the migration process. Migrate.dll detects the component locations of the target application. Windows 2000 Setup then provides the working and source directories to the Migrate.dll.
MigrateUser9x | Setup | Setup calls the MigrateUser9x function once for each Windows 95/98 user account on the computer being upgraded. Setup also calls MigrateUser9x once for the Windows 2000 Administrator account (that is, the active user account becomes the Windows 2000 Administrator account after migration). Setup also calls MigrateUser9x for the default user account if necessary. If the application is installed for the given user name, Migrate.dll gathers user-specific application information to be used during the MigrateUserNT function call.
MigrateSystem9x | Setup | Gather system-wide information concerning the target application for Migrate.dll and to save private data to be used during the MigrateSystemNT function call.
DllMain (DLL_PROCESS_DETACH) | Windows 95/98 | Unload the migration DLL.

During the second phase of Windows 2000 Setup (that is, when the newly installed Windows 2000 is running), the following Migrate.dll functions are called in the order listed.

Function | Caller | Reason for Call
DllMain (DLL_PROCESS_ATTACH) | Windows 2000 | Load the migration DLL.
InitializeNT | Setup | Provide the migration DLL with its working directory, specified during the earlier call to Initialize9x.
MigrateUserNT | Setup | Enable the migration DLL to make changes to a user's application settings. Setup calls this function once for each user. Note that the number of calls may be less than the number made to MigrateUser9x because some user accounts might not migrate. For example, the default user account might not migrate if that account has never been accessed. As such, a DLL must store its private data on a per-user basis.
MigrateSystemNT | Setup | Change the system application settings based on the information obtained during the call to MigrateSystem9x.
DllMain (DLL_PROCESS_DETACH) | Windows 2000 | Unload the migration DLL.

When the system calls the DllMain (DLL_PROCESS_ATTACH) function in graphical user interface mode, Setup has completed the following:

  1. Copied all 32-bit executables from %WinDir%\System to %WinDir%\System32.
  2. Adjusted Window 95/98 registry key values within HKU\User\Software and HKLM\Software that contain full paths to files that exist in a new location on Windows 2000.
  3. Migrated all system settings, including the registry, program menu items, desktop, recent documents, and other user-interface settings.
  4. Deleted Windows 95/98-specific COM system objects (not application objects).
  5. Migrated the user's shell folders (such as C:\Windows\Desktop) to the Windows 2000 equivalent (that is, C:\Windows\Profiles\<user>\Desktop).
  6. Adjusted the paths in .stf files (part of ACME Setup) if necessary.
  7. Adjusted links and program information files (or PIFs) that point to moved files.

Note In the Windows 2000 phase of the upgrade process, each DLL function has 60 seconds to complete its processing. If it takes longer, Setup terminates it.


Migrate.inf

During the Windows 95/98 phase of the upgrade, Windows 2000 Setup creates and uses Migrate.inf files to collect file information from all migration DLLs. During the Windows 2000 phase of the upgrade, Setup uses these same files to provide file information back to the submitting migration DLLs.

Each working directory passed to a migration DLL has a Migrate.inf file in it. The .inf file sections are shown in the following list:

  • [Version]
  • [Migration Paths]
  • [Excluded Paths]
  • [Handled]
  • [Moved]
  • [Incompatible Messages]
  • [<Message Object>]
  • [Windows NT Disk Space Requirements] Section


[Version] Section

This is a generic section required for every Windows 95/98-style INF. The [Version] section contains information about the version of Windows 2000 being used for the upgrade. Your DLL cannot modify this section. The [Version] section contains the following parameters.

Signature = <File Signature>
File Signature is the signature of the file. For example, $Windows NT$. This is the default.
SetupOS = <OS Identifier>
OS Identifier specifies the operating system. For the upgrade, this value is Microsoft® Windows® 2000 Operating System.
SetupPlatform = <Platform Identifier>
Platform Identifier specifies the Windows 2000 platform upgrade object. The value can be either Workstation or Server.
SetupBuild = <Build Identifier>
Build Identifier specifies the Windows 2000 build upgrade object. This value is 1382 or higher (depending on the build).


[Migration Paths] Section

This section contains a list of Win32 paths to files requested by your migration DLL through the ExeNamesBuf parameter of the QueryVersion function. Each line represents the full path to a file. Setup writes to this section.

Your migration DLL can read the file paths listed here using the SetupGetLineCount and SetupGetLineText functions.

If multiple copies of a particular file name are found (such as versions installed by other applications), multiple paths to the file name are listed in this section. When this happens, the migration DLL for your application must determine which executables are valid for migrating your application.

If a file is not found in the active Windows 95/98 system, it is not listed.


[Excluded Paths] Section

This section contains a list of paths that are not part of the active Windows 95/98 system configuration. Setup does not search through any of these paths or their subdirectories. Excluded paths include directories on the system drive used by other operating systems, network drives, and substituted or compressed drives. Setup writes to this section.

If your application is installed in any of the paths listed in this section, your DLL must return ERROR_NOT_INSTALLED when initializing.

Your migration DLL can read the paths listed in this section using the SetupGetLineCount and SetupGetLineText functions. You can then use string matching to determine if a path you need is excluded. Your DLL must never make changes to the directories listed in this section.


[Handled] Section

Use this section to inform Windows 2000 Setup about files, directories, and registry entries in the active Windows 95/98 installation you intend to handle using your migration DLL.

Setup assumes that files, directories, and registry entries listed here are compatible with Windows 2000. Therefore, Setup does not warn users about incompatibilities associated with these components and does not perform any processing. For example, specifying a path to a file in the System folder ensures that the file will not be moved to the System32 folder. Similarly, handled registry entries are not copied to Windows 2000.

All file names, directories, and registry entries listed in this section must be valid on the active Windows 95/98 system.

You can use the WritePrivateProfileString function to add lines to this section.

The syntax for this section is:

<Identifier Object> = <Identifier Type>
Identifier Object
Specifies the name or path to a Windows 95/98 file, directory, or registry location. Files and directories are in long file name format. Registry paths are of the form:

<Root>\<SubKey>\<SubKey>\<…> [<Value Name>]

where:

Root
Specifies the registry root. It can be any one of HKEY_LOCAL_MACHINE, HKLM, HKEY_ROOT, or HKR. Migration DLLs can only handle a registry key for all users, not for individual users.
SubKey
Specifies one or more registry keys separated by backslashes (\).
Value Name
Optional. Specifies a registry value name enclosed in square brackets. An empty square bracket ([ ]) specifies the default value for the specified key name.

Registry keys or value names themselves can contain square brackets ([ ]), tildes (~), or characters with values greater than 127. You must enclose hexadecimal values for these characters in tildes (~) when writing them as registry values to the [Handled] section. For more information, see Handling Special String Characters.

Identifier Type
Identifies the type of <Identifier Object> to be handled. It must be one of the following three values:
File
The object specified refers to a long file name (including the full path to the file). This must be a full path, without environment variables and without short versions of long file names.
Directory
The object specified refers to a directory (including the full path to the directory).
Registry
The object specified refers to a registry key (including the full path to that key).
Report
Indicates Object is a registry location. This type causes Setup to continue to process Object, but not display messages associated with Object in the incompatibility report.


[Moved] Section

Use this section to inform Windows 2000 Setup about files and directories you plan to move, rename, or delete during the migration. This enables Setup to adjust the relevant Windows 2000 Explorer shell links.

You can use the WritePrivateProfileString function to add lines to this section. Listing a file here ensures that it is not processed any other way. This behavior is the same in the [Handled] section.

The syntax for this section is:

<OldPath> = <NewPath>
OldPath
Specifies the file name or path of a Windows 95/98 file or directory to be moved or deleted. File names and paths are in long file name format.
NewPath
Specifies the new file name or path in long file name format. If NewPath is empty or not specified, Setup assumes the migration DLL has deleted the entry.


[Incompatible Messages] Section

Use this section to present messages to a user through the Setup incompatibility report (displayed during the Windows 95/98 phase of the upgrade process). The incompatibility report is presented to the user before any changes are made to the computer. The report is useful when you intend to change the behavior of an application or when you plan to remove application components.

The syntax for this section is:

<Message Object Section> = <Message>
Message Object Section
Specifies the name of a custom section (defined by your migration DLL) that contains a list of message objects such as files, directories, and registry entries. The name may be any combination of uppercase and lowercase letters, numbers, and spaces. It cannot start or end with a space. By listing one or more message objects in a separate section, the migration DLL for your application can associate several message objects with a single message. The value for Message Object Section is used as the component string in the incompatibility report presented to the user.
Message
Specifies a string describing the details of the incompatibility report or message displayed to the user. The user sees the text in a multiline, scrollable, read-only edit control.

For example, this incompatibility section might contain the following line:

MyAppMsg = "The MS-DOS and Real-mode portions of Myapp.exe are not supported on Windows NT"

Where MyAppMsg refers to another section containing the list of files, directories, and registry entries associated with the message string.

Remarks

When you write an entry to the [Incompatible Messages] section, a Message Object Section must provide one or more objects associated with the message.

Your migration DLL is responsible for managing the code page and language dependencies of the messages listed in this section. In particular, the text in the [Incompatible Messages] section must be in the same language as the active Windows 95/98 system. The migration DLL for your application must not write messages to this section if the DLL does not support the active operating system language.

The user has an option to view, print, or save the incompatibility report generated. This report associates the ProductID with each Message.


[<Message Object>] Section

This section provides a mechanism for you to associate one or more message objects (such as file, directory, and registry location) with a message specified in the [Incompatible Messages] section. The [Handled] section describes how to specify a message object.

The section name is defined by your migration DLL. Each line has the following syntax:

<Message Object> = <Identifier Type>
Message Object
Specifies a Windows 95/98 file, path, or registry entry. A file or path must be specified in long file name format.
Identifier Type
Identifies the type of <Message Object>. This parameter can only have one of the following values.
Value | Definition
File | The object specified refers to a long file name (including the full path to the file).
Directory | The object specified refers to a directory (including the full path to the directory).
Registry | The object specified refers to a registry key (including the full path to that key).
IniFile | Indicates Object is an INI file section, or an INI key within a section.
GUID | Indicates Object is a COM-based GUID.
UserName | Indicates Object is a user name.
AnswerFile | Indicates Object is an answer file entry.
Report | Indicates Object is a registry location, but is used for the report only, and not for any other purpose.
ProductID | Indicates Object is the DLL's Product ID. Messages associated with the Product ID cannot be suppressed.

Remarks

Setup uses the value you substitute for Message Object to develop a hierarchy for incompatibility messages. The use of the section name enables the migration DLL for your application to organize multiple incompatibility messages in the same format that Setup uses. Setup processes the section name in one of two ways:

  • If the name of the section matches ProductID, Setup displays the message at the root level of the incompatibility message tree. The ProductID itself is listed in a tree control, and, when the user clicks the root item, the incompatibility message is shown in an edit control.
  • If the name of the section contains one or more backslashes, Setup separates the string at the backslashes to create the hierarchy. Setup limits the number levels in the tree to 10. Optimally, you should organize your messages into no more than three levels.

    Using the section name in this way creates a unique path for each migration DLL, organized under a single item at the root. Because the [<Message Object>] section is used for display purposes, your DLL must provide localized strings.

Setup treats all objects in a section as a set. If every object in the set is found in any [Handled] section (including those provided by other vendors), no incompatibility message is displayed for that particular object, even if the message is listed in the [Incompatible Messages] section. If only some or none of the objects are handled, the message is displayed.


[Windows NT Disk Space Requirements] Section

Use this section to specify the amount of disk space (on a per-drive basis) that your migration DLL requires during the Windows 2000 phase of the upgrade. Setup uses this information to calculate the total amount of space required for the upgrade. If sufficient space is not available, Setup informs the user during the Windows 95/98 phase of the upgrade.

The syntax for this section is:

<DriveLetter> = <Space Required>
DriveLetter
Specifies the drive and partition (single letter without a colon or backslash) in which a migration DLL requires space for its private data. Setup ignores drives and partitions that are also listed in the [Excluded Paths] section.
Space Required
Specifies an integer that indicates the amount of disk space in (bytes) required by a migration DLL during the Windows 2000 phase of Setup. When calculating space requirements, the amount of space lost from directory and cluster use must be taken into account. The number does not include the files copied into the working directory during the Windows 95/98 phase.

If this section is not present, or if no drives or partitions are specified, Setup assumes that the migration DLL requires no additional hard disk space to migrate the target application.

Important Be sure to specify the correct disk space requirement data. If you cannot calculate disk space requirements accurately, you should provide a liberal estimate of the space required.


Using the Migration-Extension Interface

Because a migration DLL is a standard Microsoft® Win32® DLL, writing one is fairly straightforward. However, there are a number of things to keep in mind:

  • There is no guaranteed processing order for migration DLLs. Therefore, do not allow one of your migration DLLs to be dependent on the migration DLL for another application.
  • The network is available to Setup during the Microsoft® Windows® 95/98 phase of the upgrade process, but it is not available during the Microsoft® Windows® 2000 phase. Your migration DLL must not try to access the network during the Windows 2000 phase of the migration.
  • Each migration DLL is copied to a unique working directory. The migration DLL for your application can store private Windows 95/98 configuration information in this directory as well as other run-time or data files required for the migration. This directory is the only location to which your migration DLL should write when it is running on Windows 95/98. Setup deletes this working directory after all migration DLLs have completed and after Windows 2000 is successfully installed.
  • The GUI-mode phase of Windows 2000 Setup can be restarted in case of a critical interruption (such as a power failure) during the upgrade. The migration DLL for your application should be prepared to handle this scenario. For example, before moving files the DLL must determine whether the file has already been moved. Of course, this is standard programming practice, and the extent of your fail-safe functionality is mostly determined by the complexity of your migration process.

The following sections detail some additional development issues to consider:

  • Where to Place Migration DLLs
  • Run-Time DLLs Included with Windows 2000
  • Manipulating a User's Registry Settings
  • Avoiding User Interfaces
  • Handling Special String Characters
  • Using the Setup Answer File
  • Deferring Application Migration
  • Logging Errors
  • Using the Win32 Profile APIs
  • Sample Migrate.inf File
  • Testing a Migration DLL


Where to Place Migration DLLs

You can place your migration DLL in a network location, on a floppy disk, or on a compact disc.

Via Location Specified in the Registry

Setup copies all migration DLLs specified in the registry to a temporary directory under %windir%\setup, and processes each migration DLL as if the user supplied it from a floppy disk.

The migration DLL locations are stored in the registry under the following key:

HKLM\Software\Microsoft\Windows\CurrentVersion\Setup\Migration DLLs

Under this registry key are zero or more values where the Value Name is the same as the migration DLL's ProductID, and the Value Data is a REG_SZ string providing the complete path to the migration DLL, excluding the file name (migrate.dll).

The migration DLLs pre-configured in the registry appear in the migration DLL user interface, and the user is allowed to remove a DLL before it is processed.

Network Location of Migrate.dll

A user can place migration DLLs on a network share and specify the location during Setup. If Setup is running in unattended mode, the user can specify the location in the Setup answer file. Each migration DLL must be placed in its own subdirectory, along with any other files required for migrating the target application.

Note If the Win95upg subdirectory exists before Setup runs, Setup deletes it and creates a new one into which the specified files are copied.

Floppy Disk- or Compact Disc-Based Migrate.dll

Setup provides users with the option to supply a floppy disk or compact disc that contains migration DLLs for their target applications. Setup searches the provided media for Migrate.dll files. For each DLL it finds, Setup copies the directory containing the DLL (and all other files and subdirectories in that directory) to a unique subdirectory.

Note The Windows 2000 compact disc also contains migration DLLs.


Run-Time DLLs Included with Windows 2000

Before running any migration extensions on the Windows 95/98 system, Setup copies the following files from the Windows 2000 compact disc to the Windows 95/98 System directory.

File | Description
Setupapi.dll | Setup
Msvcrt.dll | Run-time shipped with Microsoft® Visual C++® 5.0
Msvcrt40.dll | Run-time shipped with Microsoft Visual C++ 4.0
Mfc40.dll | Microsoft Foundation Class Library 4.0
Mfc42.dll | Microsoft Foundation Class Library 4.2

For international environments, Setup copies the appropriate localized DLLs. For example, Setup copies Mfc40jpn.dll and Mfc42jpn.dll for a Japanese installation.

Debug versions of the run-time DLLs are not copied, and Setup cannot guarantee that other run-time versions of an application will migrate correctly.

This list of files is not final. Setup can also install newer versions if they become available. However, if your migration extension requires a run-time DLL that is not installed by Windows 2000, you must ship the run-time DLL with your migration DLL and use the functionality of the migration DLL to ensure the run-time DLL is installed.


Manipulating a User's Registry Settings

Setup runs in a logged-on user context under Windows 95/98. On Windows 2000, Setup runs in the local system account context. As such, the migration DLL for your application should not attempt to query or modify the HKEY_CURRENT_USER registry key directly. Instead, the migration DLL should query the UserRegKey handles passed to it through the MigrateUser9x and MigrateUserNT functions.


Determining Application Registry Differences

You can use SysDiff.exe to determine registry entry differences between an application on a computer with Windows 2000 newly installed and on a computer upgraded from Windows 95/98. SysDiff.exe is available in the Microsoft Windows NT Workstation 4.0 Resource Kit. This utility is useful when you are not familiar with the application registry differences between the two versions of your application.

The following procedure describes how to determine application registry differences:

To use SysDiff.exe to determine the registry entries made by an application on a computer using Windows 2000

  1. Install Windows 2000 on a computer.
  2. Log on to the system under the administrator account.
  3. Copy SysDiff.exe and SysDiff.inf into a temporary directory.
  4. Modify SysDiff.inf as necessary.
  5. From the Command Prompt, run
    sysdiff /snap [/log:<logfile1>] <snap_file>

    The logfile1 and snap_file parameters are valid file names. The /log parameter is optional. SysDiff.exe creates both files.

  6. Install your application.

    SysDiff.exe records all system changes.

  7. From the command prompt, run
    sysdiff /diff [/log:<logfile2>] <snap_file> <diff_file>

    The logfile2 and diff_file parameters are valid file names. The /log parameter is optional. SysDiff.exe creates both files. The snap_file parameter is the file name you specified in the previous call to SysDiff.exe.

  8. From the command prompt, run
    sysdiff /dump <diff_file> <dump_file>

    The dump_file parameter is a valid file name. SysDiff.exe creates it. The diff_file parameter is the file name you specified in the previous call to SysDiff.exe.

    When SysDiff.exe completes, dump_file is a plain text file containing a list of file, .ini file, and registry changes made to the system by the target application.

The following procedure describes how to get the upgrade registry entries:

To determine registry entry differences between an upgraded computer (from Windows 95/ 98 to Windows 2000) and a computer with Windows 2000 newly installed

  1. Install Windows 95/98 on a computer.
  2. Install your application.
  3. Upgrade the computer using Winnt32.exe.
  4. Log on to the Windows 2000 computer.
  5. Run RegEdit32.exe or RegEdit.exe.
  6. Compare the registry values listed in dump_file obtained during the final call to SysDiff.exe and those listed in the registry. The differences are those you need to resolve.

Note The second procedure is different because SysDiff.exe does not work across platforms.


Migrating Device Drivers

The answer file provided to your migration DLL can be used to install Windows 2000 compatible device drivers for a particular device.

To install Windows 2000 compatible device drivers for a particular device using the answer file

  1. Create a section named [DeviceDrivers] in the answer file provided to it during the MigrateSystem9x function call.
  2. Copy all the drivers (including INFs and other files) to their own subdirectory in the working directory provided to your DLL.
  3. Write the following line (or lines depending on the number of unique PNP IDs to be migrated) in the [DeviceDrivers] section:

    <PNP ID of device> = <Full path to device INF>

    where

    <PNP ID of device> specifies the hardware or compatible ID for the device

    <Full path to device INF> specifies the full path to the installation INF for the device. Note that the path specified cannot point to the original media location.

In general, several PNP ID lines will point to the same installation INF.


Avoiding User Interfaces

The migration DLL for your application should not have a user interface. A parent window handle is provided only for the extreme case where a user interface is unavoidable. If Setup provides a NULL parent window handle, the DLL must never display any windows, dialog boxes, drop-down list boxes, or message boxes. The migration DLL must never display a user interface during the Windows 2000 phase of Setup.

This is extremely important when Setup is running in unattended mode. You can determine the Setup mode by testing the value of the ParentWnd parameter in either MigrateUser9x or MigrateSystem9x.

The installation process should be as hassle free as possible. If the user interface is required at any point during an attended installation, consider the usability implications when someone must load multiple migration DLLs.


Handling Special String Characters

When writing messages, paths, and registry locations to an INF file, the migration DLL for your application might pass certain characters that have special meanings to Setup and to the operating system. When writing messages or paths, the string must be enclosed in double-quotes if it contains any of the following:

"

%

,

;

[

]

In addition, embedded percentage and double-quote characters must be formatted properly before the string is written to the INF file.

Example

This "example" illustrates how to escape the percentage (%) symbol

Must appear in an INF file as

"This ""example"" illustrates how to escape the percentage (%%) symbol"

When writing registry locations to an INF file, you must replace the characters listed below as well as all characters with ASCII values greater than 127 (including double-byte characters) with their hexadecimal values enclosed in tilde (~).

Character | Hex value
" | 0x22
% | 0x25
, | 0x2C
; | 0x3B
[ | 0x5B
] | 0x5D
~ | 0x7E

For example, replace a semicolon (;) with the string ~3B~ .


Using the Setup Answer File

Setup passes the location of its answer file (typically Unattend.txt) to the migration DLL for your application in the MigrateUser9x, MigrateSystem9x, MigrateUserNT, and MigrateSystemNT functions.

The migration DLL for your application can modify this answer file during the Windows 95/98 phase of the upgrade process by using the Win32® profile functions (such as WritePrivateProfileString). The migration DLL is permitted to change standard answer file settings and create private sections for its own use. The migration DLL cannot modify the following sections of the Unattend.txt file:

[Unattended]]
[MassStorageDrivers]
[DisplayDrivers]
[KeyboardDrivers]
[PointingDeviceDrivers]
[OemBootFiles]
[OEM_Ads]
[GuiUnattended]
[UserData]
[LicenseFilePrintData]
[Display]
[Modem]

Remarks

For a detailed description of answer file parameters, search the Microsoft Knowledge Base

If you require a private section, the migration DLL for your application should build the section name from the working directory passed to it by the Initialize9x function. The private section name can only contain alphanumeric characters (A-Z and 0-9). Spaces and other characters are not permitted because they prevent Windows 2000 Setup from starting the text-only phase of the installation.

During the Windows 2000 phase of the upgrade, the migration DLL for your application must treat the Unattend.txt file as a read-only file. You must not modify the answer file in any way.


Windows 95 and Windows 98 Upgrade Answer File Parameters

To support the Migration-Extension Interface, the Windows 95/98 Upgrade section has been added to the Unattend.txt answer file.

[Win9xUpg]

Boot16 = [Yes|No]
Default value is No. Enables MS-DOS boot mode.
DefaultPassword = <password>
This value is optional. Provides a default password for all local accounts created during a migration process. Since Setup cannot migrate the Windows passwords of users when upgrading a system, it must assign passwords for those created accounts. When Setup needs to assign one of these passwords, it first checks to see if a UserPassword entry for that user exists. If not, it uses the value of this key if specified. There are some security concerns about using this key since the password is stored as plain text within the Unattend.txt file. All passwords in the answer file are automatically deleted after the upgrade. If a local account needs to be created for a user with a UserPassword entry and no DefaultPassword is specified, Setup creates a random password. After the first reboot, the user is prompted to enter a password for all users created during Setup.
DomainJoinText = <HTML text>
This value is optional. Inserts the HTML text on the Domain Join page of the GUI-mode Setup wizard. The only supported HTML tags are anchor (<A>) and bold (<B>).
ForcePasswordChange = [Yes|No]
Default value is Yes. This value is optional. Instructs Setup to automatically require a password change on all local accounts it creates during the migration process. When a user first logs on using one of these accounts, the user is informed that the current password has expired. The user is forced to select a new password before logging on.
ForceWorkgroup = [Yes|No]
Default value is No. Instructs Setup to skip domain checks and to run the computer in Workgroup mode after the upgrade.
IgnoreNetworkErrors = [Yes|No]
Default value is No. Instructs Setup not to retry a domain that fails. If this parameter is set to Yes the setup is completely unattended; however, if this parameter is set to Yes, the domain account migration may fail.
KeepBadLinks = [Yes|No]
Default value is Yes. Instructs Setup to keep all links. Setting this parameter to No removes incompatible links.
MigrateDefaultUser = [Yes|No]
Default value is Yes. This value is optional. Causes Setup to migrate the default Windows 95 or Windows 98 user account settings to the default Windows 2000 user account. If this parameter is set to No, the Win9x default user settings are not maintained. Subsequent user accounts created on the computer will inherit Windows 2000 defaults. Some applications rely on settings migrated to the default user. These applications may not work unless default user migration is enabled. This key should be used in special cases only (for example, when it is known that no applications require default user migration).
MigrateUsersAsAdmin = [Yes|No]
Default value is Yes. This value is optional. Causes Setup to add all accounts that it creates during migration to the Local Administrators group, giving those users full control over the computer. If users are not migrated as administrators, some migrated applications and settings may not work properly after the upgrade is completed. For more information about group-level security settings, see Windows 2000 help.
MigrateUsersAsPowerUser = [Yes|No]
Default value is Yes. This value is optional. Causes Setup to add all accounts that it creates during migration to the Power Users group, giving the new users in the Power Users group more permissions than users in the Users group, but fewer permissions than users in the Administrators group. Power Users can perform an any operating system task except tasks reserved for the Administrators group. For more information about group-level security settings, see Windows 2000 Help.
MigrationDlls = <migration dll path> [, <migration dll path>, ...]
This value is optional. Specifies the location of upgrade packs that Setup needs to copy and process during an upgrade to Windows 2000. If multiple paths are specified, commas must separate the paths. Setup searches each of these paths, including its subfolders, for upgrade packs. Multiple upgrade packs can be located at a single location, but each upgrade pack must exist in its own subfolder of that single path. Do not put more than one upgrade pack in a single folder. An upgrade pack consists of a migration .dll file (Migrate.dll) and any additional files that may be required to properly upgrade a particular software component from Windows 95 or Windows 98 to Windows 2000.
ReportOnly = [Yes|No]
Default value is No. This value is optional. Instructs Setup to generate an upgrade report and then exit without making any changes to the current Windows 95 or Windows 98 installation. The upgrade report contains a list of hardware and software incompatibilities and is saved to the root of the system drive if the SaveReportTo key is not specified.
SafeMode = [Yes|No]
Default value is No. When set to Yes, this parameter instructs Setup to maintain a list of settings during the upgrade. If any setting causes Windows 95/98 to hang or crash, that setting is skipped during the next setup. Using this parameter slows Setup but allows Setup to skip certain types of malfunctioning software installed on Windows 95/98. Safe mode is started automatically if a problem is detected. If SafeMode = Off, Setup must be run three times. If SafeMode = Yes, Setup need only be run two times.
SaveReportTo = <path to report>
Value is optional. Specifies the full path and file name of the upgrade report (text file) generated by Setup. If the Windows 95 or Windows 98 installation has network connectivity, the <path to report> can be a UNC path. System environment variables enclosed in percent signs (%) can be used in the path. If the special environment variable %computername% is specified in the path, the resulting file name contains the actual computer name. This is useful when upgrade reports are being collected from several Windows 95 or Windows 98 computers to a central location.
ScanDrives = [drive][,drive,drive]
This value is optional. Enables scanning of drives that are normally skipped. This parameter is used with ReportOnly and allows software on network drives to be checked. For more information, see the "ReportOnly" section.
UseLocalAccountOnError = [Yes|No]
The default value is No. This value is optional. Directs Setup to create a local account if a network account cannot be automatically determined or resolved. This is only valid on computers with the Microsoft Networking Client software installed. Windows 95 and Windows 98 only keep the domain of the last logged in user in the registry. Because neither Windows 95 nor Windows 98 keep the domains of other users who may have logged on to the computer, Windows 2000 Setup searches all trusted domains on the network by default. Windows 2000 Setup automatically uses a domain account when an exact match is found. If a user is not found on any trusted domain or if the user account is found on two or more domains on the network, a dialog box appears prompting the person performing the upgrade to resolve the conflict. This dialog box also appears if network errors occur. Specifying UseLocalAccountOnError = Yes in the Unattend.txt file ensures a complete unattended installation. This causes Setup to create a local account whenever a network account cannot be automatically resolved. A user with a local account may not have his or her original network privileges. In addition, if a computer cannot be added to the computer domain during installation of the network on Windows 2000, all user accounts change to local accounts. For more information, see the "UserDomain" section.
UserDomain = <domain name>, <user name> [, <user name>, <user name>, ...]
This value is optional. Specifies the user domain for a user. Multiple UserDomain lines can be used to specify different domains for different users. When specified, this key prevents Setup from searching all trusted domains on the network for a matching user account. (The search process can be time-consuming if a large number of trusted domains exist on the network.) If the account is not found in the specified domain, either because the account does not exist or the domain is not accessible, a dialog box appears prompting the user to resolve the account unless the UseLocalAccountOnError key is set to Yes. For more information, see "UseLocalAccountOnError," earlier in this document.
UserPassword = <user>, <password> [,<user>,<password>,...]
This value is optional. Provides Setup with the names of the passwords to create for specific local accounts. Because Setup cannot migrate the Windows passwords of users when upgrading a system, it must create passwords for non-domain accounts during the migration process. Using this key, an administrator can predetermine what those passwords are for specific users. There are some security concerns about using this key since the password is stored as plain text within the answer file. However, after the upgrade is completed, all the password keys are deleted from the copy of the answer file left on the computer. The original copy of the answer file with which you started Setup is not deleted. If a local account needs to be created for a user without a UserPassword entry and no DefaultPassword is specified, Setup creates a random password. After the first reboot, the user is prompted to enter a password for all users created during Setup. For more information, see the "DefaultPassword" section.


Deferring Application Migration

If your application is network-based, it might not be practical for your application's migration DLL to copy your migration files from a network location to every local computer that has Windows 95/98 installed.

Instead, the migration DLL can redirect the application shell links to a new executable. This way, when a user starts the application, the new executable runs instead. This executable is responsible for completing the migration from the network location to that user's local computer in the user's logged-on, network-accessible context on Windows 2000. If you choose this approach, the migration DLL must only copy the new executable to the local hard disk and redirect all shell links from the original target application to this new executable. You accomplish this through an entry in the [Moved] Section of Migrate.inf.

The new executable must complete the migration when a user runs it on Windows 2000. The executable must restore the original shell links, delete itself, and then run the newly migrated application. For more details on how to replace links, see the Shell Link documentation in the Platform SDK.


Logging Errors

Windows 2000 Setup automatically logs errors returned by your application's migration DLL code. To log the errors that the migration DLL detects, you must use the new Setup API SetupLogError function.


Using the Win32 Profile APIs

The Win32 Profile functions (GetPrivateProfileString and WritePrivateProfileString) use a separate cache than the one used by SetupOpenInfFile. Therefore, if you open Migrate.inf using SetupOpenInfFile, and then (before closing it) modify the file using WritePrivateProfileString, your changes do not appear in the SetupOpenInfFile cache.

As such, care must be taken when using both the Win32 Profile functions and the Setup functions. Ideally, their use should be separated.

If you modify Migrate.inf using WritePrivateProfileString, you must call WritePrivateProfileString again with all NULL parameters to force the file to be written to disk before you open it again using SetupOpenInfFile.

If a file has already been opened with SetupOpenInfFile, do not call WritePrivateProfileString to modify the same file.


Sample Migrate.inf File

;
; Sample migrate.inf file
;
[Version]
Signature = $Windows NT$
SetupOS = Microsoft(R) Windows NT(R) Operating System
SetupPlatform = Workstation
SetupBuild = 1610

[Migration Paths]
"c:\windows\sample.exe"
"c:\temp\sample.exe"
"C:\program files\sample\bar.exe"
"C:\samplefiles\bar.exe"

[Excluded Paths]
"c:\winnt40"
"f:\"

[Handled]
"C:\windows\sample.exe"=File
"C:\windows\sample.dll"=File
"c:\Program Files\sample"=Path
"HKLM\Software\Sample-Bar, Inc."=Registry

[Moved]
;moved
"c:\dir\example.exe"="c:\dir\nt\example.exe"

;moved and replaced
"c:\Windows\sample.exe"="c:\Windows\sample\sample_nt.exe"

;deleted
"c:\Windows\sample\Win9x"=""

[Incompatible Messages]
;the message must be on one line, but can be long
Sample-Bar ="The application Sample-Bar does not support the MS-DOS component 'example' on Windows NT."

[Sample-Bar]
"C:\dir\example.exe"=File
"C:\dir\example.dll"=File

[Windows NT Disk Space Requirements]
c=104096
d=16384


Testing a Migration DLL

Applications that do not survive migration from one version of Microsoft Windows to another will not comply with the Certified for Microsoft Windows Logo requirements. Your application's migration DLL can help preserve your logo compliance. For more information about the logo program, see http://msdn.microsoft.com/certification/description.asp.

The Setup program attempts to detect conflicts that arise from implementing your application under the new operating system. It may or may not succeed in identifying inconsistencies. Because of this, you should test your application extensively under various migration scenarios.

The migration functionality is provided to help you ensure that your customer base can use your application under the new operating system. You should test how your application performs under different versions of Windows. Ideally, it performs the same under different versions.

If conflicts exist, you have two options. You can either correct the intrinsic problem so that no problems occur during migration, or you can create a migration DLL. If you do not take advantage of the Migration-Extension Interface, your customers must reinstall your application before it can run correctly under the newly installed system.

Migration DLLs must be thoroughly tested before being distributed to end-users by means of the World Wide Web or other media. The following procedures outline the minimal process you should undertake during your test. Note that you should repeat the tests for multiple user account scenarios (that is, default, roaming, workgroup, and domain users). The scenarios should also cover combinations of these user accounts.

The following procedure describes how to test your application's migration DLL during an attended upgrade:

To test your application's migration DLL during an attended upgrade

  1. Install Windows 95/98 on a computer.
  2. Install the target application on the computer.
  3. Start Windows 2000 Setup and select Upgrade from the Welcome page.
  4. When prompted, insert the media containing the migration DLL.
  5. Complete Windows 2000 Setup.
  6. Start the migrated application on Windows 2000.
  7. Run any test suites to determine if the application is fully functional.

The following procedure describes how to test your application's migration DLL during an unattended upgrade:

To test your application's migration DLL during an unattended upgrade

  1. Install Windows 95/98 on a computer.
  2. Install the target application on the computer.
  3. Place the migration DLL in a subdirectory of %WinDir%\Setup\Win95upg.
  4. Start Windows 2000 Setup in unattended mode with the "Win95Upgrade = Yes" key set in the answer file.
  5. Complete Windows 2000 Setup.
  6. Start the migrated application on Windows 2000.
  7. Run any test suites to determine if the application is fully functional.


Migration-Extension Interface Reference

You call the Migrate.dll functions in the following order as you migrate your application from Microsoft® Windows® 95 and Windows 98 to Windows 2000.

  1. QueryVersion
  2. Initialize9x
  3. MigrateUser9x
  4. MigrateSystem9x
  5. InitializeNT
  6. MigrateUserNT
  7. MigrateSystemNT


Initialize9x

Initialize9x is the second function called by Setup. Its primary function is to initialize the migration DLL before the migration operation begins.

LONG CALLBACK Initialize9x(
  LPCSTR WorkingDirectory,
  LPCSTR SourceDirectories,
  LPCSTR MediaDirectory
);

Parameters

WorkingDirectory
[in] Pointer to the path of a Setup-supplied directory your application's migration DLL can use to store its private temporary data. This directory contains the Migrate.dll file and all associated files. The migration DLL must write to this directory if it needs temporary data storage. Setup provides this directory again during the Windows 2000 phase of the upgrade process and automatically deletes the directory after the upgrade is complete.
SourceDirectories
[in] Pointer to the path of the Windows 2000 installation files. This path is a multi-sz string you can use to specify multiple source directories. Normally, this directory is D:\I386 where D:\ is the CD-ROM drive on the computer.
MediaDirectory
[in] Specifies the path to the original media directory. This is the same as the current directory path when QueryVersion was called.

Return Values

ERROR_SUCCESS
Your application's migration DLL found one or more installed components for the target application.

– Or –

Your application's migration DLL does not attempt to detect installed components in Initialize9x.

ERROR_NOT_INSTALLED
Your application's migration DLL initializes properly but does not find any of its components installed on the active Windows 95 or Windows 98 installation. Note that Setup will not call your DLL again if this value is returned.

Remarks

Setup calls the Initialize9x function after relocating your application's migration DLL to the local hard disk. During this call, the migration DLL should attempt to detect its new installation. The migration DLL should return ERROR_SUCCESS if it is ready to be called by Setup during the Windows 2000 phase of the upgrade. If the DLL returns ERROR_NOT_INSTALLED, Setup stops processing it.

All return values other than ERROR_SUCCESS and ERROR_NOT_INSTALLED are Win32 error values and are considered initialization errors. Setup reports the error to the user, cleans up the migration DLL files, and prompts the user to continue or cancel the Windows 2000 installation process.

Exceptions generated by the migration DLL cause Setup to report Remote Procedure Call (RPC) error messages. Setup provides more information in SetupErr.log.

The current directory is set to the working directory and is not changed by Setup during the processing of a migration DLL.


InitializeNT

The InitializeNT function is called during Windows 2000 GUI Mode Setup when the Windows 2000 phase of the upgrade is ready to start.

LONG CALLBACK InitializeNT(
  LPCWSTR WorkingDirectory,
  LPCWSTR SourceDirectories,
  LPVOID Reserved
);

Parameters

WorkingDirectory
[in] Pointer to the path of the Setup-supplied working directory. This value is the value that your migration DLL used for storing its private temporary data and files during the Windows 95/98 phase of the upgrade.
SourceDirectories
[in] Pointer to the path of the Windows 2000 installation files. This path is of type multi-sz because multiple source directories can be provided. Normally this directory is D:\I386 or C:\$WIN_NT$.~LS\I386, where D:\ is the CD-ROM drive on the computer and C:\$WIN_NT$.~LS\I386 is the Setup temporary source directory.
Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS
Your application's migration DLL initializes properly within the Windows 2000 environment.

Remarks

The InitializeNT function is called during Windows 2000 GUI Mode Setup when the Windows 2000 phase of application migration is ready to start. When this function is called, the active directory is set to the DLL working directory.

The migration DLL is loaded, calling DllMain along with DLL_PROCESS_ATTACH, and remains loaded for the calls to InitializeNT, MigrateUserNT and MigrateSystemNT. Setup unloads the DLL after MigrateSystemNT completes, calling DllMain along with DLL_PROCESS_DETACH.

Your application's migration DLL must not display user messages in its InitializeNT function.

All return values other than ERROR_SUCCESS are Win32 error values and are considered critical errors. Setup reports the error to the user and then stops processing your migration DLL. However, Setup does not continue the upgrade. Any errors or logs generated include the ProductID string specified in QueryVersion to identify your DLL.

Exceptions generated by your migration DLL cause Setup to report Remote Procedure Call (RPC) error messages. Setup provides more information in SetupErr.log.


MigrateSystem9x

The MigrateSystem9x function gathers system-wide information concerning the target application and saves private data to be used during the later call to MigrateSystemNT.

LONG CALLBACK MigrateSystem9x(
  HWND ParentWnd,
  LPCSTR AnswerFile,
  LPVOID Reserved
);

Parameters

ParentWnd
[in] Handle to the parent window for any dialog boxes or windows that you want your application's migration DLL to display.

You should not display a user interface unless absolutely necessary.

If this parameter value is NULL, Setup is running in an unattended mode, and the migration DLL must not prompt the user for input. The ParentWnd value determines whether ERROR_CANCELLED can be returned from this function.

AnswerFile
[in] Pointer to a copy of the Windows 2000 Setup answer file, (typically Unattend.txt). This file is used to automate the installation of Windows 2000 and can be accessed using the Win32 profile functions, such as GetPrivateProfileString and WritePrivateProfileString. For more information, see Using the Setup Answer File.
Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS
The target application is installed on the system.

– Or –

System-wide changes are necessary for the target application during the Windows 2000 phase of the upgrade.

ERROR_NOT_INSTALLED
The migration DLL detects no application components common to the entire system or the DLL requires no further processing. Note that Setup continues to call MigrateUser9x for the rest of the users and MigrateSystem9x if this function returns ERROR_NOT_INSTALLED.
ERROR_CANCELLED
The user elects to exit the Setup program. Use this return value only if ParentWnd is not NULL.

Remarks

Your DLL must always check for the value in the ParentWnd parameter of the MigrateSystem9x function before proceeding; its value determines whether user interface elements can be displayed to the user.

Do not use MigrateSystem9x to modify the system. Use it for system-wide information gathering only. To modify system-wide settings, save any private data collected in the working directory of the migration DLL (specified in an earlier call to Initialize9x). Use MigrateSystemNT to perform the modifications during the Windows 2000 phase of the upgrade.

All return values other than ERROR_SUCCESS, ERROR_NOT_INSTALLED, and ERROR_CANCELLED are Win32 error values and are considered initialization errors. Setup reports the error to the user and prompts the user to continue or cancel the upgrade.

Exceptions generated by your migration DLL cause Setup to report RPC error messages. Setup provides more information in SetupErr.log.

See Also

GetPrivateProfileString, Initialize9x, MigrateSystemNT, MigrateUser9x, WritePrivateProfileString


MigrateSystemNT

The MigrateSystemNT function migrates system-wide settings.

LONG CALLBACK MigrateSystemNT(
  HINF UnattendInfHandle,
  LPVOID Reserved
);

Parameters

UnattendInfHandle
[in] Supplies a valid INF handle that can be used with the Setup APIs to access the unattend.txt file. This file contains settings supplied by the user, settings generated by Setup, and settings generated by migration DLLs. A migration DLL must not close this handle
Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS
The migration of system-wide settings is successful.

Remarks

Your application's migration DLL is responsible for managing its private data created and stored during the call to the MigrateSystem9x function and processed during the call to the MigrateSystemNT function.

The migration DLL must not display user messages in its MigrateSystemNT function.

Return values other than ERROR_SUCCESS terminate the processing of your migration DLL. However, Windows 2000 Setup does proceed. Ideally, only critical problems (such as a hardware failure) should generate termination of error codes.

Exceptions generated by your migration DLL cause Setup to report Remote Procedure Call (RPC) error messages. Setup provides more information in SetupErr.log.


MigrateUser9x

The MigrateUser9x function gathers information concerning the users and saves private data to be used during the later call to MigrateUserNT .

LONG CALLBACK MigrateUser9x(
  HWND ParentWnd,
  LPCSTR AnswerFile,
  HKEY UserRegKey,
  LPCSTR UserName,
  LPVOID Reserved
);

Parameters

ParentWnd
[in] Specifies a handle to the parent window for any dialog boxes or windows that you may want your migration DLL to display.

You should not display a user interface unless absolutely necessary.

If this parameter is NULL, Setup is running in an unattended mode, and your DLL must not display user interface elements or prompt the user for input.

AnswerFile
[in] Pointer to a copy of the Windows 2000 Setup answer file (typically Unattend.txt), which is used to automate the installation of Windows 2000. You can access this file using the Win32 profile functions (for example, GetPrivateProfileString and WritePrivateProfileString). Some sections of this answer file cannot be modified by your DLL. For more information, see Using the Setup Answer File.
UserRegKey
[in] Handle to the user's registry hive for the Windows 95/98 user specified in the UserName parameter. This user hive is equivalent to the user's HKEY_CURRENT_USER (HKCU) setting when that user logs on. This handle is valid only within the scope of MigrateUser9x and is provided for user-specific information gathering purposes.
UserName
[in] Provides the user name (for example, "username") for the Windows 95/98 user whose registry information is supplied through the UserRegKey parameter. A value of NULL refers to the default Windows 95/98 user account (that is, the account used when a user accesses the system by skipping the logon process). The value passed by the UserName parameter may also be Administrator even though Windows 95/98 do not have an administrator account. This allows a migration DLL to collect information for the Windows 2000 Administrator account to be created later.
Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS
The target application is installed for the specified user.

– Or –

Your application's migration DLL needs further processing during the Windows 2000 phase.

ERROR_NOT_INSTALLED
The target application is not installed for the specified user account and that user's registry does not require any processing. Note that Setup continues to call MigrateUser9x for the rest of the users and MigrateSystem9x if this value is returned.
ERROR_CANCELLED
The user wants to exit Setup. You should specify this return value only if ParentWnd is not set to NULL.

Remarks

A DLL must always check for the value of ParentWnd in the MigrateUser9x function before proceeding, since the value of this function determines whether the user interface can be displayed to the user.

Do not use the MigrateUser9x function to modify the user account. Use it only for gathering information about user accounts. To modify user-specific settings, save the data collected to the working directory provided and then use the MigrateUserNT function to perform the modifications.

Use the DLL working directory provided by the Initialize9x WorkingDirectory parameter to store any user-specific configuration information you want to track. Remember to use the UserName parameter to differentiate the information about the various users.

All return values other than ERROR_SUCCESS, ERROR_NOT_INSTALLED, and ERROR_CANCELLED are Win32 error values and are considered initialization errors. Setup reports the error to the user and prompts the user to continue or cancel the upgrade.

Exceptions generated by your migration DLL cause Setup to report Remote Procedure Call (RPC) error messages. Setup provides more information in SetupErr.log.

See Also

GetPrivateProfileString, Initialize9x, MigrateSystem9x, MigrateUserNT, WritePrivateProfileString


MigrateUserNT

The MigrateUserNT function migrates the user accounts that port from Windows 95/98 to Windows 2000.

LONG CALLBACK MigrateUserNT(
  HINF AnswerFileHandle,
  HKEY UserRegKey,
  LPCWSTR UserName,
  LPVOID Reserved
);

Parameters

AnswerFileHandle
[in] Handle to the INF answer file being used for the upgrade process. This file contains settings generated by Setup, the attending user, and all migration DLLs. You can access the file referenced by this handle using the Setup functions. Do not close this handle at any time.
UserRegKey
[in] Handle to the private registry settings of the Windows 95/98 user specified in UserName. This handle is equivalent to the HKEY_CURRENT_USER (HKCU) setting when that user is logged on. The handle is only valid within the scope of MigrateUserNT. Do not close this handle at any time.
UserName
[in] The same user name passed to MigrateUser9x. If this value is NULL, Setup is referring to the logon user. If the Windows 9x logon user settings are valid, they are used for the logon prompt settings. In addition to the user name, the following strings are appended in multi-sz style:

Domain – Specifies the domain for the user, if any, otherwise an empty string.

FixedUserName – Specifies the user name as it will exist on Windows 2000. This name is different from UserName only when UserName contains invalid characters.

Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS
The migration of user-specific settings is successful.

Remarks

The order in which user names are passed to your application's migration DLL during the call to MigrateUserNT can be different than the order in which they were passed during the call to MigrateUser9x.

Setup can disable migration of one or more user accounts if errors occur. For this reason, the number of user names passed to MigrateUserNT may be less than the number passed to MigrateUser9x.

Your application's migration DLL is responsible for managing its private data created and stored during the call to MigrateUser9x and processed during the call to MigrateUserNT.

Your migration DLL must not display user messages within its MigrateUserNT function.

Return values other than ERROR_SUCCESS terminate the processing of your application's migration DLL. However, Windows 2000 Setup does proceed. Ideally, only critical problems (such as a hardware failure) should generate termination of error codes.

Exceptions generated by your migration DLL cause Setup to report Remote Procedure Call (RPC) error messages. Setup provides more information in SetupErr.log.

See Also

MigrateUser9x


QueryVersion

QueryVersion is the first function called by Setup. The parameters of this function return identification information such as the migration DLL's product ID and version number.

LONG CALLBACK QueryVersion(
  LPCSTR *ProductID,
  LPUINT DllVersion,
  LPINT *CodePageArray,
  LPCSTR *ExeNamesBuf,
  PVENDORINFO *VendorInfo
);

Parameters

ProductID
[out] Pointer to a string that identifies the DLL and its target application. To ensure uniqueness, the string must contain the name of the manufacturer, the product name, and the version number of the application the DLL will migrate. The length of the string must not exceed MAX_PATH bytes (as defined within your application's migration DLL). Setup ignores excess characters. The ProductID string is also used for error messages generated during DLL processing.

Your application's migration DLL is responsible for allocating and freeing the ProductID string buffer.

DllVersion
[out] Pointer to a non-zero, unsigned integer that specifies the version number of your application's migration DLL. Setup looks for duplicates by comparing ProductID strings from other migration DLLs. If two or more DLLs have identical ProductID strings, Setup uses the DLL with the highest DllVersion number and ignores the other duplicates.

The value passed in DllVersion is not intended to be the DLL binary version number.

CodePageArray
[out, optional] Pointer to an array of integers containing all the code pages supported by the migration DLL. The last element of the array must be – 1. If your application's migration DLL does not support the system code page, Setup skips the migration DLL, and your application will not migrate to the new operating system.

If this pointer is NULL, Setup processes all the required functions in the DLL regardless of the installed Windows 95/98 code pages. Set this pointer to NULL if the DLL has no language dependencies.

Your DLL is responsible for allocating and freeing memory used by this array.

ExeNamesBuf
[out, optional] Pointer to a multi-sz string buffer containing a list of file names (not paths) that your application's migration DLL wants Setup to locate. Setup locates all instances of the listed files and returns the list of full file paths to your migration DLL via the Migrate.inf file. Paths to files located on network, substituted, and compressed drives are not returned to the DLL because Setup does not search these drives. Other directories on the computer not related to the active Windows 95/98 installation may also be excluded.

Set this parameter to NULL if you do not want Setup to search for any particular files.

Your migration DLL is responsible for allocating and freeing the ExeNamesBuf string buffer.

VendorInfo
[out] Receives a pointer to the DLL-allocated VENDORINFO structure. This structure is defined as:
typedef struct {
    CHAR CompanyName[256];
    CHAR SupportNumber[256];
    CHAR SupportUrl[256];
    CHAR InstructionsToUser[1024];
} VENDORINFO, *PVENDORINFO;

Setup requires data in at least one field. When the migration DLL generates an error, the information in this structure is displayed to the user. This information may also be used elsewhere in the Windows 2000 Setup user interface.

Return Values

ERROR_SUCCESS
Your application's migration DLL found one or more installed components for its target application. This guarantees that Setup will call your migration DLL for later processing.

– Or –

Your application's migration DLL does not attempt to detect installed components in QueryVersion.

ERROR_NOT_INSTALLED
Return this value if the migration DLL did not find any installed components. This error is defined in the Windows 2000 version of Setupapi.h and is the value 0xE0001000. If the DLL does not attempt to detect installed components in QueryVersion, return ERROR_SUCCESS.

Remarks

Setup uses the QueryVersion function to determine if further processing of the DLL is necessary. During this call, your application's migration DLL (located on a floppy disk, compact disc, or network share) must provide Setup with the ProductID, DllVersion, CodePageArray, and ExeNamesBuf information. At this point, the migration DLL cannot make any changes to the system.

The migration DLL should attempt to determine if the target application is installed on the computer and then return the appropriate result from QueryVersion. The system unloads the migration DLL after QueryVersion returns. Setup copies the migration DLL to the local hard disk and calls Initialize9x only if QueryVersion returns ERROR_SUCCESS.

All return values other than ERROR_SUCCESS and ERROR_NOT_INSTALLED are Win32 error values and are considered initialization errors. Setup reports the error to the user, cleans up your migration DLL files, and prompts the user to continue or cancel the Windows 2000 installation process.

An exception generated by a migration DLL causes Setup to report Remote Procedure Call (RPC) error messages. Setup provides more information in SetupErr.log.

During the call to QueryVersion, Setup finds all occurrences of files listed in the ExeNamesBuf string (if not NULL) and writes their locations to the [Migration Paths] section of the Migrate.inf file. These paths are then available to the other functions in your migration DLL.

Setup detects duplicate migration DLLs by comparing the ProductID strings of supplied DLLs. Setup only processes the DLL with the highest DllVersion number. The user is not notified of duplicates found.

Important DllVersion number zero (0) is reserved for migration DLLs supplied by Windows 2000. Setup DLLs not supplied by Windows 2000 on the Windows 2000 compact disc must not use this value.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.